<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
<head>
	<title>Rendering views</title>
  <link rel="stylesheet" type="text/css" href="documentation.css" />
</head>
<body>
<h1>Rendering views</h1>
<p>When a controller handles a GET type request, it will normally display some HTML. A great part of the application is therefore associated with rendering this HTML markup. The HTML -- or more generally: the output of the application -- is referred to as the <em>view</em> in the MVC terminology. While Konstrukt tries not to lock you into a specific solution for rendering the view, it provides a basic, minimalistic, solution.</p>
<h2>Using templates</h2>
<p>The controller features a few helper methods, for rendering output. In very simple cases, you can simply return a string from the <code>GET()</code> method, but string building becomes tedious and messy soon enough. If you already use a template engine, you may want to continue using that. In that case, simply instantiate the template engine and use it from within the handler method of the controller. Konstrukt offers a minimalistic, no-frills alternative to a full-blown template engine. The method <code>render()</code>, which we have already seen in the previous examples, simply includes a PHP-file, buffers the output and returns it as a string. A technique also known as <a href="http://thephppro.com/articles/pte.php">&quot;using PHP as a template engine&quot;</a>. The Konstrukt implementation has a few additional tricks up the sleeve.</p>
<p>The first argument to <code>render()</code> is the file name to include. Calling render with just this argument, is analogous to the following:</p>
<pre class="php"><span class="kw3">ob_start</span><span class="br0">&#40;</span><span class="br0">&#41;</span>;
<span class="kw1">include</span> <span class="st0">'filename'</span>;
<span class="kw1">return</span> <span class="kw3">ob_get_clean</span><span class="br0">&#40;</span><span class="br0">&#41;</span>;</pre><p>Using <code>render(&#039;filename&#039;)</code> thus saves you three lines of code.</p>
<div class="note">Note: I use the terms <strong>controller</strong> and <strong>view</strong> on the basis of the <a href="http://www.phpwact.org/pattern/model_view_controller">MVC pattern</a>. Simply put, the <strong>controller</strong> is the part of the code, which interprets user input, while <strong>view</strong> is the part of the code, which generates output. In Konstrukt, the separation of the two isn&#039;t strictly enforced; It&#039;s up to the developer to keep the degree of separation, which is desirable.</div>
<h3>Getting data to the view</h3>
<p>Including the file is only the first step though; Templates usually use dynamic data to render the output. There are basically two ways of accomplishing this -- Either you <em>push</em> data to the template, or you let the template <em>pull</em> the data it needs. The first technique is the most straight forward. Inside the controller, you can pass the data to the template by using the optional second argument to <code>render()</code>. The argument should be an associative array, which is then expanded into the scope of the template. This means that the keys of the array becomes variables in the scope of the template.</p>
<p>Given the following example:</p>
<pre class="php"><span class="kw2">class</span> MyController <span class="kw2">extends</span> k_Controller
<span class="br0">&#123;</span>
  <span class="kw2">function</span> GET<span class="br0">&#40;</span><span class="br0">&#41;</span> <span class="br0">&#123;</span>
    <span class="re0">$params</span> = <span class="kw3">Array</span><span class="br0">&#40;</span><span class="st0">'foo'</span> =&gt; <span class="st0">'value of foo'</span><span class="br0">&#41;</span>;
    <span class="kw1">return</span> <span class="re0">$this</span>-&gt;<span class="me1">render</span><span class="br0">&#40;</span><span class="st0">&quot;templates/foo.tpl.php&quot;</span>, <span class="re0">$params</span><span class="br0">&#41;</span>;
  <span class="br0">&#125;</span>
<span class="br0">&#125;</span></pre><p>And the following being the contents of the file <code>templates/foo.tpl.php</code>:</p>
<pre class="php"><span class="kw2">&lt;?php</span>
<span class="kw3">echo</span> <span class="re0">$foo</span>;
<span class="kw2">?&gt;</span></pre><p>Will output: <code>value of foo</code></p>
<h3>Pulling data</h3>
<p>The other method of getting dynamic data into the view, is to let the template itself pull the data it needs. Since the template is really just an included file, you can use <code>$this</code> from within the template, to refer to the controller. This makes it easy to get your hands on the data that you need.</p>
<p>This method is useful for decoupling controller and view from each other, but makes the view less reusable. It also imposes a greater responsibility on the programmer, to refrain from updating data from the template. In a properly view-controller separated application, the view is only rendering output -- it should <strong>never</strong> change anything.</p>
<p>It depends on the particular needs of your application, which method you prefer to use -- And you can of course mix them.</p>
<h2>Generating URLs</h2>
<p><code>k_Controller</code> has two methods which are often used by the template. The most important of these, is the <code>url()</code> method, which generates a URL relative to the controller. Since the controller is resolved at runtime, the URL may not be known, making this method quite handy.</p>
<p>Generating URLs to itself isn&#039;t the only thing <code>url()</code> is capable of. If you pass a string as the first argument, you&#039;ll get a URL relative to the current. You can use <code>..</code> to move a level up, or prepend with a <code>/</code> to get a URL relative to the top level of the application. <code>url()</code> also takes an optional second argument, which is an associative array of values, that are encoded as querystring parameters. Querystring parameters can also be set for the whole controller, in the <code>$urlState</code> property. This can be used for controllers with view state, such as GET-based forms etc. For an example of use, you can see the <code>k_DataList</code> class. Explicit parameters in the <code>url()</code> method take precedence over <code>$urlState</code>. These are fairly advanced topics though.</p>
<p>A couple of example uses for <code>url()</code>:</p>
<pre class="php"><span class="co1">// Assuming the current controller refers to &quot;foo&quot;, relative to the root &quot;http://example.org/&quot;</span>
<span class="kw3">assert</span><span class="br0">&#40;</span><span class="re0">$this</span>-&gt;<span class="me1">url</span><span class="br0">&#40;</span><span class="br0">&#41;</span> == <span class="st0">&quot;http://example.org/foo&quot;</span><span class="br0">&#41;</span>;
<span class="kw3">assert</span><span class="br0">&#40;</span><span class="re0">$this</span>-&gt;<span class="me1">url</span><span class="br0">&#40;</span><span class="st0">&quot;bar&quot;</span><span class="br0">&#41;</span> == <span class="st0">&quot;http://example.org/foo/bar&quot;</span><span class="br0">&#41;</span>;
<span class="kw3">assert</span><span class="br0">&#40;</span><span class="re0">$this</span>-&gt;<span class="me1">url</span><span class="br0">&#40;</span><span class="st0">&quot;..&quot;</span><span class="br0">&#41;</span> == <span class="st0">&quot;http://example.org/&quot;</span><span class="br0">&#41;</span>;
<span class="kw3">assert</span><span class="br0">&#40;</span><span class="re0">$this</span>-&gt;<span class="me1">url</span><span class="br0">&#40;</span><span class="st0">&quot;/&quot;</span><span class="br0">&#41;</span> == <span class="st0">&quot;http://example.org/&quot;</span><span class="br0">&#41;</span>;
&nbsp;
<span class="kw3">assert</span><span class="br0">&#40;</span><span class="re0">$this</span>-&gt;<span class="me1">url</span><span class="br0">&#40;</span><span class="kw2">null</span>, <span class="kw3">Array</span><span class="br0">&#40;</span><span class="st0">'qux'</span> =&gt; <span class="st0">'47'</span><span class="br0">&#41;</span><span class="br0">&#41;</span> == <span class="st0">&quot;http://example.org/foo?qux=47&quot;</span><span class="br0">&#41;</span>;
<span class="re0">$this</span>-&gt;<span class="me1">urlState</span><span class="br0">&#91;</span><span class="st0">'qux'</span><span class="br0">&#93;</span> = <span class="st0">'53'</span>;
<span class="kw3">assert</span><span class="br0">&#40;</span><span class="re0">$this</span>-&gt;<span class="me1">url</span><span class="br0">&#40;</span><span class="br0">&#41;</span> == <span class="st0">&quot;http://example.org/foo?qux=53&quot;</span><span class="br0">&#41;</span>;
<span class="kw3">assert</span><span class="br0">&#40;</span><span class="re0">$this</span>-&gt;<span class="me1">url</span><span class="br0">&#40;</span><span class="kw2">null</span>, <span class="kw3">Array</span><span class="br0">&#40;</span><span class="st0">'qux'</span> =&gt; <span class="st0">'47'</span><span class="br0">&#41;</span><span class="br0">&#41;</span> == <span class="st0">&quot;http://example.org/foo?qux=47&quot;</span><span class="br0">&#41;</span>;
<span class="kw3">assert</span><span class="br0">&#40;</span><span class="re0">$this</span>-&gt;<span class="me1">url</span><span class="br0">&#40;</span><span class="kw2">null</span>, <span class="kw3">Array</span><span class="br0">&#40;</span><span class="st0">'qux'</span> =&gt; <span class="kw2">null</span><span class="br0">&#41;</span><span class="br0">&#41;</span> == <span class="st0">&quot;http://example.org/foo&quot;</span><span class="br0">&#41;</span>;</pre><h2>Translation</h2>
<p>In an effort to encourage developers to detach localised string constants, Konstrukt features a built-in mechanism for translation. This feature is completely optional, and if you use an external templating engine, it may not already supply something similar.</p>
<p>The way it works, is that instead of hardcoding language-specific strings into your application, you should use the translation function <code>__()</code>, supplied by the controller. If a translation exists for the string parameter, it is returned. Otherwise, the input string is simply returned. This makes it transparent to use, which means that you can implement the feature even if you&#039;re not making a multi-lingual application from the outset.</p>
<p>The default implementation of translation is to look strings up in an associative array <code>$i18n</code>. To supply a translation for your controller, you simply put translations in this mapping. Where the translations come from is beyond the scope of Konstrukt, but they would typically be loaded from a configuration file, or the database. If a translation isn&#039;t found, the controller recurses up to the context controller. That way, you can put generic translations in a top-level controller (such as the <em>Root</em>), and more specific translations in deeper nested controllers. This also makes it easy to implement your own translation service, by overriding the <code>__()</code> function in your root controller.</p>
<pre class="php"><span class="kw2">class</span> MyController <span class="kw2">extends</span> k_Controller
<span class="br0">&#123;</span>
  <span class="kw2">protected</span> <span class="re0">$i18n</span> = <span class="kw3">Array</span><span class="br0">&#40;</span>
    <span class="st0">'hello world'</span> =&gt; <span class="st0">'hej verden'</span>
  <span class="br0">&#41;</span>;
  <span class="kw2">function</span> GET<span class="br0">&#40;</span><span class="br0">&#41;</span> <span class="br0">&#123;</span>
    <span class="kw1">return</span> <span class="re0">$this</span>-&gt;__<span class="br0">&#40;</span><span class="st0">&quot;hello world&quot;</span><span class="br0">&#41;</span>;
  <span class="br0">&#125;</span>
<span class="br0">&#125;</span></pre><h2>The document</h2>
<p>When building HTML applications, you will need to set certain values for the entire HTML document. This includes the <code>&lt;title&gt;</code> and inclusion of style sheets and javascript files. The registry contains an object for holding these values -- the <code>k_Document</code>. You can access the document through all controllers in the hierarchy, by referring to <code>$this-&gt;document</code>. For example, to set the title of the rendering view:</p>
<pre class="php"><span class="kw2">class</span> MyController <span class="kw2">extends</span> k_Controller
<span class="br0">&#123;</span>
  <span class="kw2">function</span> GET<span class="br0">&#40;</span><span class="br0">&#41;</span> <span class="br0">&#123;</span>
    <span class="re0">$this</span>-&gt;<span class="me1">document</span>-&gt;<span class="me1">title</span> = <span class="st0">&quot;My Title&quot;</span>;
  <span class="br0">&#125;</span>
<span class="br0">&#125;</span></pre><p>Or to include a style sheet:</p>
<pre class="php"><span class="kw2">class</span> MyController <span class="kw2">extends</span> k_Controller
<span class="br0">&#123;</span>
  <span class="kw2">function</span> GET<span class="br0">&#40;</span><span class="br0">&#41;</span> <span class="br0">&#123;</span>
    <span class="re0">$this</span>-&gt;<span class="me1">document</span>-&gt;<span class="me1">styles</span><span class="br0">&#91;</span><span class="br0">&#93;</span> = <span class="re0">$this</span>-&gt;<span class="me1">url</span><span class="br0">&#40;</span><span class="st0">&quot;/css/somestyle.css&quot;</span><span class="br0">&#41;</span>;
  <span class="br0">&#125;</span>
<span class="br0">&#125;</span></pre><p>The document is used by the root controller to render the outermost part of the HTML document -- The <code>doctype</code> and <code>&lt;head&gt;</code> tags. Before the dispatcher can render the document, you must supply a template to use, by setting the <code>$template</code> property of the document. You can do this in the constructor of your root controller:</p>
<pre class="php"><span class="kw2">class</span> Root <span class="kw2">extends</span> k_Dispatcher
<span class="br0">&#123;</span>
  <span class="kw2">function</span> __construct<span class="br0">&#40;</span><span class="br0">&#41;</span> <span class="br0">&#123;</span>
    <span class="kw2">parent</span>::__construct<span class="br0">&#40;</span><span class="br0">&#41;</span>;
    <span class="re0">$this</span>-&gt;<span class="me1">document</span>-&gt;<span class="me1">template</span> = <span class="st0">&quot;../templates/document.tpl.php&quot;</span>;
  <span class="br0">&#125;</span>
...</pre><div class="note">Note: <code>k_Document</code> has a property <code>$encoding</code>, which is used to specify the character encoding in the HTML. This property should always match the actual encoding used for serving the document over HTTP. It is <strong>highly</strong> recommended to leave this as the default UTF-8.</div>
<h2>Using the hierarchy</h2>
<p>Because of Konstrukts nested controllers, the hierarchy is often used in the view rendering phase to render common sections of the final view. An example of this technique can be observed in the <code>k_Dispatcher</code>&#039;s use of the document. The child controller is embedded inside a wrap of HTML. This can be used for generating repeated HTML wrapping in your application. The most common use is for navigational elements.</p>
<p>To wrap the result of child controllers, simply override the handleRequest method of the parent controller to embed the result in some HTML. The following example should illustrate how:</p>
<pre class="php"><span class="kw2">class</span> MyController <span class="kw2">extends</span> k_Controller
<span class="br0">&#123;</span>
  <span class="kw2">public</span> <span class="re0">$map</span> = <span class="kw3">Array</span><span class="br0">&#40;</span>
    <span class="st0">&quot;foo&quot;</span> =&gt; <span class="st0">&quot;MyController2&quot;</span>,
  <span class="br0">&#41;</span>;
&nbsp;
  <span class="kw2">function</span> handleRequest<span class="br0">&#40;</span><span class="br0">&#41;</span> <span class="br0">&#123;</span>
    <span class="kw1">return</span> <span class="re0">$this</span>-&gt;<span class="me1">render</span><span class="br0">&#40;</span><span class="st0">&quot;../templates/navigation.tpl.php&quot;</span>, <span class="kw3">Array</span><span class="br0">&#40;</span><span class="st0">'content'</span> =&gt; <span class="kw2">parent</span>::<span class="me2">handleRequest</span><span class="br0">&#40;</span><span class="br0">&#41;</span><span class="br0">&#41;</span><span class="br0">&#41;</span>;
  <span class="br0">&#125;</span>
<span class="br0">&#125;</span></pre><p>And the contents of <code>../templates/navigation.tpl.php</code>:</p>
<pre class="php">&lt;ul <span class="kw2">class</span>=<span class="st0">&quot;menu&quot;</span>&gt;
<span class="kw2">&lt;?php</span> <span class="kw1">foreach</span> <span class="br0">&#40;</span><span class="kw3">array_keys</span><span class="br0">&#40;</span><span class="re0">$this</span>-&gt;<span class="me1">map</span><span class="br0">&#41;</span> <span class="kw1">as</span> <span class="re0">$name</span><span class="br0">&#41;</span>: <span class="kw2">?&gt;</span>
  &lt;li&gt;&lt;a href=<span class="st0">&quot;&lt;?php echo htmlspecialchars($this-&gt;url($name)); ?&gt;&quot;</span>&gt;&lt;?php <span class="kw3">echo</span> <span class="kw3">htmlspecialchars</span><span class="br0">&#40;</span><span class="re0">$name</span><span class="br0">&#41;</span>; ?&gt;&lt;/a&gt;&lt;/li&gt;
<span class="kw2">&lt;?php</span> <span class="kw1">endforeach</span>; <span class="kw2">?&gt;</span>
&lt;/ul&gt;
&lt;div <span class="kw2">class</span>=<span class="st0">&quot;content&quot;</span>&gt;
<span class="kw2">&lt;?php</span> <span class="kw3">echo</span> <span class="re0">$content</span>; <span class="kw2">?&gt;</span>
&lt;/div&gt;</pre><p>Note that because abnormal responses (Such as a redirect) are generated with exceptions, they will circumvent the normal rendering call stack. Therefore, you can safely wrap the result of child controllers, since they will only return during normal rendering.</p>
<h2>Convenience Methods</h2>
<p>Whenever you echo out a variable in HTML, you need to escape any HTML specialcharacters (&amp; &lt; and &gt;). Since it&#039;s rather longwinded to write <code>echo htmlspecialchars</code> all the time, Konstrukt offers a convenient regular function for this. Likewise, it offers a regular function <code>url</code> which is synonymous to calling <code>$this-&gt;url</code>, and there is a <code>__</code>, which corresponds to <code>$this-&gt;__</code>. You could thus write the above code as:</p>
<pre class="php">&lt;ul <span class="kw2">class</span>=<span class="st0">&quot;menu&quot;</span>&gt;
<span class="kw2">&lt;?php</span> <span class="kw1">foreach</span> <span class="br0">&#40;</span><span class="kw3">array_keys</span><span class="br0">&#40;</span><span class="re0">$this</span>-&gt;<span class="me1">map</span><span class="br0">&#41;</span> <span class="kw1">as</span> <span class="re0">$name</span><span class="br0">&#41;</span>: <span class="kw2">?&gt;</span>
  &lt;li&gt;&lt;a href=<span class="st0">&quot;&lt;?php e(url($name)); ?&gt;&quot;</span>&gt;&lt;?php e<span class="br0">&#40;</span><span class="re0">$name</span><span class="br0">&#41;</span>; ?&gt;&lt;/a&gt;&lt;/li&gt;
<span class="kw2">&lt;?php</span> <span class="kw1">endforeach</span>; <span class="kw2">?&gt;</span>
&lt;/ul&gt;
&lt;div <span class="kw2">class</span>=<span class="st0">&quot;content&quot;</span>&gt;
<span class="kw2">&lt;?php</span> <span class="kw3">echo</span> <span class="re0">$content</span>; <span class="kw2">?&gt;</span>
&lt;/div&gt;</pre><p>These functions look like regular, static functions, but are in fact dynamically mapped to call back to methods on the current rendering controller.</p>
</body>
</html>